Subject: Migration from former X/Open CPI-C to CPI-C 2.0

From: [email-masked]
Date: Fri, 4 Mar 94 13:20:28 +0100

At the December CIW meeting I took the task to formulate an appendix
to the CPI-C 2.0 document describing the application migration from
former X/Open CPI-C to CPI-C 2.0.

I cannot send this appendix as change request to the CIW because
the negotiations about the CIW member agreement between IBM and
Siemens failed. But all the same I send it to ciw-general for
the CIW's early view.

Siemens Nixdorf submitted my proposal as change request to X/Open.
So I hope we will discuss it at the March CIW meeting.

The line and page numbers match to the X/Open version of the CPI-C 2.0
document.

Regards
Peter

------------------------------------------------------------------
 
Title:          Migration from former X/Open CPI-C to CPI-C 2.0
 
Qualifier:      Major editorial
 
Rationale:      Add an appendix to the document that describes the  
		application migration from the former X/Open CPI-C
		to CPI-C 2.0.
 
Proposed change:

  Add the following text behind line 100 (chapter 1.3):

    . Appendix H

      This appendix describes the application migration from former X/Open
      CPI-C (X/Open Developer's Specification: CPI-C 1990) to CPI-C 2.0.

  Add a new column to table 1-1 on pages 9 to 11 (chapter 1.5.6)
  describing the valid CPI-C calls in the former X/Open CPI-C.

  Relabel the existing appendix H to appendix I.

  Add the following new appendix H:

    Appendix H: Application Migration from former X/Open CPI-C to CPI-C 2.0
  
    This appendix describes the application migration from former X/Open CPI-C
    (X/Open Developer's Specification: CPI-C 1990) to CPI-C 2.0.
  
    -  Accept_Conversation (CMACCP) behaves differently when there exists
       no incoming conversation. CPI-C 2.0 returns CM_PROGRAM_STATE_CHECK,
       X/Open CPI-C returns CM_OPERATION_INCOMPLETE and a conversation_ID.
       Programs which want to accept multiple conversations should
       use the following calls instead of Accept_Conversation:
       - Initialize_For_Incoming (CMINIC)
       - Set_Processing_Mode (CMSPM), processing_mode = CM_NON_BLOCKING
       - Accept_Incoming (CMACCI).
       As examples flows 7 and 8 in the X/Open Developer's Specification
       pages 34 to 37 must be changed.
    
    -  All conversation specific calls except Cancel_Conversation (CMCANC)
       return a CM_OPERATION_NOT_ACCEPTED return code instead of
       CM_PROGRAM_STATE_CHECK, when the conversation specific call has been
       attempted after receiving a CM_OPERATION_INCOMPLETE return_code value
       to the previous conversation specific call and prior to calling
       Wait_For_Conversation (CMWAIT).
    
    -  Extract_Conversation_Security_User_ID (CMECSU) is not supported in
       CPI-C 2.0; the function is available using Extract_Security_User_ID
       (CMESUI). The name was changed to force an awareness of the
       increased length of the security_user_id.
    
    -  Convert_Incoming (CMCNVI) and Convert_Outgoing (CMCNVO) may receive
       an unexpected return_code CM_PROGRAM_PARAMETER_CHECK, if the
       string_length exceeds the maximum length permitted by the local
       implementation.
     
    -  CM_SYNC_LEVEL_NOT_SUPPORTED_PGM return_code value must be changed
       to CM_SYNC_LVL_NOT_SUPPORTED_PGM. This was a printing error in the
       X/Open Developer's Specification.
    
    -  The function specify_Local_TP_Name must be changed to
       Specify_Local_TP_Name. This was a printing error in the X/Open
       Developer's Specification.
     
    -  X/Open CPI-C describes that several processes may share the same
       conversation_ID (see page 42 in X/Open Developer's Specification).
       This is not supported by CPI-C 2.0.
     
    -  X/Open defines all functions as type CM_RETCODE
       (for example: extern CM_RETCODE CMACCP;),
       CPI-C 2.0 defines all functions as type void
       (for example: extern CM_ENTRY cmaccp;).
       Programs which test the return value of a CPI-C call have to test
       now the parameter cm_return_code.
    
    -  The readable macros (for example Accept_Conversation instead of
       CMACCP) are only available in CPI-C 2.0 if the program or the
       include file contains a line
       #define READABLE_MACROS
    
    -  Some parameters have other types in X/Open CPI-C and CPI-C 2.0.
       Some compilers may give out warnings when compiling existing
       CPI-C programs with the new CPI-C 2.0 include file.
      
				  | X/Open CPI-C    | CPI-C 2.0
       ---------------------------+-----------------+-------------------------
       Conversation ID parameter  | CONVERSATION_ID | unsigned char CM_PTR
				  | (i.e. char [8]) | (i.e. unsigned char *)
				  |                 |
       Character pointers         | char *          | unsigned char CM_PTR
				  |                 | (i.e. unsigned char *)
				  |                 |
       length parameters          | int *           | CM_INT32 CM_PTR
				  |                 | (i.e. signed long int *)
				  |                 |
       definitions of return codes| typedef enum    | #define
       and numeric parameters     |                 |

-----------------------------------------------------------------------------
Peter Binninger                         Voice: (+49) 7531-87-4758
Computer Gesellschaft Konstanz mbH      Fax:   (+49) 7531-87-4888
(Siemens Nixdorf Informationssysteme)   Email: [email-masked]
Max-Stromeyer-Strasse 116
78467 Konstanz
Germany